home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / proxy.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  8.6 KB  |  301 lines
  1. /**
  2.  * @file proxy.h Proxy API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_PROXY_H_
  26. #define _PURPLE_PROXY_H_
  27.  
  28. #include <glib.h>
  29. #include "eventloop.h"
  30.  
  31. /**
  32.  * A type of proxy connection.
  33.  */
  34. typedef enum
  35. {
  36.     PURPLE_PROXY_USE_GLOBAL = -1,  /**< Use the global proxy information. */
  37.     PURPLE_PROXY_NONE = 0,         /**< No proxy.                         */
  38.     PURPLE_PROXY_HTTP,             /**< HTTP proxy.                       */
  39.     PURPLE_PROXY_SOCKS4,           /**< SOCKS 4 proxy.                    */
  40.     PURPLE_PROXY_SOCKS5,           /**< SOCKS 5 proxy.                    */
  41.     PURPLE_PROXY_USE_ENVVAR        /**< Use environmental settings.       */
  42.  
  43. } PurpleProxyType;
  44.  
  45. /**
  46.  * Information on proxy settings.
  47.  */
  48. typedef struct
  49. {
  50.     PurpleProxyType type;   /**< The proxy type.  */
  51.  
  52.     char *host;           /**< The host.        */
  53.     int   port;           /**< The port number. */
  54.     char *username;       /**< The username.    */
  55.     char *password;       /**< The password.    */
  56.  
  57. } PurpleProxyInfo;
  58.  
  59. typedef struct _PurpleProxyConnectData PurpleProxyConnectData;
  60.  
  61. typedef void (*PurpleProxyConnectFunction)(gpointer data, gint source, const gchar *error_message);
  62.  
  63.  
  64. #include "account.h"
  65.  
  66. #ifdef __cplusplus
  67. extern "C" {
  68. #endif
  69.  
  70. /**************************************************************************/
  71. /** @name Proxy structure API                                             */
  72. /**************************************************************************/
  73. /*@{*/
  74.  
  75. /**
  76.  * Creates a proxy information structure.
  77.  *
  78.  * @return The proxy information structure.
  79.  */
  80. PurpleProxyInfo *purple_proxy_info_new(void);
  81.  
  82. /**
  83.  * Destroys a proxy information structure.
  84.  *
  85.  * @param info The proxy information structure to destroy.
  86.  */
  87. void purple_proxy_info_destroy(PurpleProxyInfo *info);
  88.  
  89. /**
  90.  * Sets the type of proxy.
  91.  *
  92.  * @param info The proxy information.
  93.  * @param type The proxy type.
  94.  */
  95. void purple_proxy_info_set_type(PurpleProxyInfo *info, PurpleProxyType type);
  96.  
  97. /**
  98.  * Sets the proxy host.
  99.  *
  100.  * @param info The proxy information.
  101.  * @param host The host.
  102.  */
  103. void purple_proxy_info_set_host(PurpleProxyInfo *info, const char *host);
  104.  
  105. /**
  106.  * Sets the proxy port.
  107.  *
  108.  * @param info The proxy information.
  109.  * @param port The port.
  110.  */
  111. void purple_proxy_info_set_port(PurpleProxyInfo *info, int port);
  112.  
  113. /**
  114.  * Sets the proxy username.
  115.  *
  116.  * @param info     The proxy information.
  117.  * @param username The username.
  118.  */
  119. void purple_proxy_info_set_username(PurpleProxyInfo *info, const char *username);
  120.  
  121. /**
  122.  * Sets the proxy password.
  123.  *
  124.  * @param info     The proxy information.
  125.  * @param password The password.
  126.  */
  127. void purple_proxy_info_set_password(PurpleProxyInfo *info, const char *password);
  128.  
  129. /**
  130.  * Returns the proxy's type.
  131.  *
  132.  * @param info The proxy information.
  133.  *
  134.  * @return The type.
  135.  */
  136. PurpleProxyType purple_proxy_info_get_type(const PurpleProxyInfo *info);
  137.  
  138. /**
  139.  * Returns the proxy's host.
  140.  *
  141.  * @param info The proxy information.
  142.  *
  143.  * @return The host.
  144.  */
  145. const char *purple_proxy_info_get_host(const PurpleProxyInfo *info);
  146.  
  147. /**
  148.  * Returns the proxy's port.
  149.  *
  150.  * @param info The proxy information.
  151.  *
  152.  * @return The port.
  153.  */
  154. int purple_proxy_info_get_port(const PurpleProxyInfo *info);
  155.  
  156. /**
  157.  * Returns the proxy's username.
  158.  *
  159.  * @param info The proxy information.
  160.  *
  161.  * @return The username.
  162.  */
  163. const char *purple_proxy_info_get_username(const PurpleProxyInfo *info);
  164.  
  165. /**
  166.  * Returns the proxy's password.
  167.  *
  168.  * @param info The proxy information.
  169.  *
  170.  * @return The password.
  171.  */
  172. const char *purple_proxy_info_get_password(const PurpleProxyInfo *info);
  173.  
  174. /*@}*/
  175.  
  176. /**************************************************************************/
  177. /** @name Global Proxy API                                                */
  178. /**************************************************************************/
  179. /*@{*/
  180.  
  181. /**
  182.  * Returns purple's global proxy information.
  183.  *
  184.  * @return The global proxy information.
  185.  */
  186. PurpleProxyInfo *purple_global_proxy_get_info(void);
  187.  
  188. /*@}*/
  189.  
  190. /**************************************************************************/
  191. /** @name Proxy API                                                       */
  192. /**************************************************************************/
  193. /*@{*/
  194.  
  195. /**
  196.  * Returns the proxy subsystem handle.
  197.  *
  198.  * @return The proxy subsystem handle.
  199.  */
  200. void *purple_proxy_get_handle(void);
  201.  
  202. /**
  203.  * Initializes the proxy subsystem.
  204.  */
  205. void purple_proxy_init(void);
  206.  
  207. /**
  208.  * Uninitializes the proxy subsystem.
  209.  */
  210. void purple_proxy_uninit(void);
  211.  
  212. /**
  213.  * Returns configuration of a proxy.
  214.  *
  215.  * @param account The account for which the configuration is needed.
  216.  *
  217.  * @return The configuration of a proxy.
  218.  */
  219. PurpleProxyInfo *purple_proxy_get_setup(PurpleAccount *account);
  220.  
  221. /**
  222.  * Makes a connection to the specified host and port.  Note that this
  223.  * function name can be misleading--although it is called "proxy
  224.  * connect," it is used for establishing any outgoing TCP connection,
  225.  * whether through a proxy or not.
  226.  *
  227.  * @param handle     A handle that should be associated with this
  228.  *                   connection attempt.  The handle can be used
  229.  *                   to cancel the connection attempt using the
  230.  *                   purple_proxy_connect_cancel_with_handle()
  231.  *                   function.
  232.  * @param account    The account making the connection.
  233.  * @param host       The destination host.
  234.  * @param port       The destination port.
  235.  * @param connect_cb The function to call when the connection is
  236.  *                   established.  If the connection failed then
  237.  *                   fd will be -1 and error message will be set
  238.  *                   to something descriptive (hopefully).
  239.  * @param data       User-defined data.
  240.  *
  241.  * @return NULL if there was an error, or a reference to a data
  242.  *         structure that can be used to cancel the pending
  243.  *         connection, if needed.
  244.  */
  245. PurpleProxyConnectData *purple_proxy_connect(void *handle,
  246.             PurpleAccount *account,
  247.             const char *host, int port,
  248.             PurpleProxyConnectFunction connect_cb, gpointer data);
  249.  
  250. /**
  251.  * Makes a connection through a SOCKS5 proxy.
  252.  *
  253.  * @param handle     A handle that should be associated with this
  254.  *                   connection attempt.  The handle can be used
  255.  *                   to cancel the connection attempt using the
  256.  *                   purple_proxy_connect_cancel_with_handle()
  257.  *                   function.
  258.  * @param gpi        The PurpleProxyInfo specifying the proxy settings
  259.  * @param host       The destination host.
  260.  * @param port       The destination port.
  261.  * @param connect_cb The function to call when the connection is
  262.  *                   established.  If the connection failed then
  263.  *                   fd will be -1 and error message will be set
  264.  *                   to something descriptive (hopefully).
  265.  * @param data       User-defined data.
  266.  *
  267.  * @return NULL if there was an error, or a reference to a data
  268.  *         structure that can be used to cancel the pending
  269.  *         connection, if needed.
  270.  */
  271. PurpleProxyConnectData *purple_proxy_connect_socks5(void *handle,
  272.             PurpleProxyInfo *gpi,
  273.             const char *host, int port,
  274.             PurpleProxyConnectFunction connect_cb, gpointer data);
  275.  
  276. /**
  277.  * Cancel an in-progress connection attempt.  This should be called
  278.  * by the PRPL if the user disables an account while it is still
  279.  * performing the initial sign on.  Or when establishing a file
  280.  * transfer, if we attempt to connect to a remote user but they
  281.  * are behind a firewall then the PRPL can cancel the connection
  282.  * attempt early rather than just letting the OS's TCP/IP stack
  283.  * time-out the connection.
  284.  */
  285. void purple_proxy_connect_cancel(PurpleProxyConnectData *connect_data);
  286.  
  287. /*
  288.  * Closes all proxy connections registered with the specified handle.
  289.  *
  290.  * @param handle The handle.
  291.  */
  292. void purple_proxy_connect_cancel_with_handle(void *handle);
  293.  
  294. /*@}*/
  295.  
  296. #ifdef __cplusplus
  297. }
  298. #endif
  299.  
  300. #endif /* _PURPLE_PROXY_H_ */
  301.